home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_apache2.idb / usr / freeware / apache2 / include / apr_xml.h.z / apr_xml.h
C/C++ Source or Header  |  2002-07-08  |  14KB  |  378 lines
  1. /* ====================================================================
  2.  * The Apache Software License, Version 1.1
  3.  *
  4.  * Copyright (c) 2000-2002 The Apache Software Foundation.  All rights
  5.  * reserved.
  6.  *
  7.  * Redistribution and use in source and binary forms, with or without
  8.  * modification, are permitted provided that the following conditions
  9.  * are met:
  10.  *
  11.  * 1. Redistributions of source code must retain the above copyright
  12.  *    notice, this list of conditions and the following disclaimer.
  13.  *
  14.  * 2. Redistributions in binary form must reproduce the above copyright
  15.  *    notice, this list of conditions and the following disclaimer in
  16.  *    the documentation and/or other materials provided with the
  17.  *    distribution.
  18.  *
  19.  * 3. The end-user documentation included with the redistribution,
  20.  *    if any, must include the following acknowledgment:
  21.  *       "This product includes software developed by the
  22.  *        Apache Software Foundation (http://www.apache.org/)."
  23.  *    Alternately, this acknowledgment may appear in the software itself,
  24.  *    if and wherever such third-party acknowledgments normally appear.
  25.  *
  26.  * 4. The names "Apache" and "Apache Software Foundation" must
  27.  *    not be used to endorse or promote products derived from this
  28.  *    software without prior written permission. For written
  29.  *    permission, please contact apache@apache.org.
  30.  *
  31.  * 5. Products derived from this software may not be called "Apache",
  32.  *    nor may "Apache" appear in their name, without prior written
  33.  *    permission of the Apache Software Foundation.
  34.  *
  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  46.  * SUCH DAMAGE.
  47.  * ====================================================================
  48.  *
  49.  * This software consists of voluntary contributions made by many
  50.  * individuals on behalf of the Apache Software Foundation.  For more
  51.  * information on the Apache Software Foundation, please see
  52.  * <http://www.apache.org/>.
  53.  */
  54. /**
  55.  * @file apr_xml.h
  56.  * @brief APR-UTIL XML Library
  57.  */
  58. #ifndef APR_XML_H
  59. #define APR_XML_H
  60.  
  61. /**
  62.  * @defgroup APR_Util_XML XML 
  63.  * @ingroup APR_Util
  64.  * @{
  65.  */
  66. #include "apr_pools.h"
  67. #include "apr_tables.h"
  68. #include "apr_file_io.h"
  69.  
  70. #include "apu.h"
  71.  
  72. #ifdef __cplusplus
  73. extern "C" {
  74. #endif
  75.  
  76. /**
  77.  * @package Apache XML library
  78.  */
  79.  
  80. /* -------------------------------------------------------------------- */
  81.  
  82. /* ### these will need to move at some point to a more logical spot */
  83.  
  84. /* simple strutures to keep a linked list of pieces of text */
  85. typedef struct apr_text apr_text;
  86.  
  87. /** Structure to keep a linked list of pieces of text */
  88. struct apr_text {
  89.     /** The current piece of text */
  90.     const char *text;
  91.     /** a pointer to the next piece of text 
  92.      *  @defvar apr_text *next */
  93.     struct apr_text *next;
  94. };
  95.  
  96. typedef struct apr_text_header apr_text_header;
  97.  
  98. /** A list of pieces of text */
  99. struct apr_text_header {
  100.     /** The first piece of text in the list */
  101.     apr_text *first;
  102.     /** The last piece of text in the list */
  103.     apr_text *last;
  104. };
  105.  
  106. /**
  107.  * Append a piece of text to the end of a list
  108.  * @param p The pool to allocate out of
  109.  * @param hdr The text header to append to
  110.  * @param text The new text to append
  111.  */
  112. APU_DECLARE(void) apr_text_append(apr_pool_t *p, apr_text_header *hdr,
  113.                                   const char *text);
  114.  
  115.  
  116. /* --------------------------------------------------------------------
  117. **
  118. ** XML PARSING
  119. */
  120.  
  121. /*
  122. ** Qualified namespace values
  123. **
  124. ** APR_XML_NS_DAV_ID
  125. **    We always insert the "DAV:" namespace URI at the head of the
  126. **    namespace array. This means that it will always be at ID==0,
  127. **    making it much easier to test for.
  128. **
  129. ** APR_XML_NS_NONE
  130. **    This special ID is used for two situations:
  131. **
  132. **    1) The namespace prefix begins with "xml" (and we do not know
  133. **       what it means). Namespace prefixes with "xml" (any case) as
  134. **       their first three characters are reserved by the XML Namespaces
  135. **       specification for future use. mod_dav will pass these through
  136. **       unchanged. When this identifier is used, the prefix is LEFT in
  137. **       the element/attribute name. Downstream processing should not
  138. **       prepend another prefix.
  139. **
  140. **    2) The element/attribute does not have a namespace.
  141. **
  142. **       a) No prefix was used, and a default namespace has not been
  143. **          defined.
  144. **       b) No prefix was used, and the default namespace was specified
  145. **          to mean "no namespace". This is done with a namespace
  146. **          declaration of:  xmlns=""
  147. **          (this declaration is typically used to override a previous
  148. **          specification for the default namespace)
  149. **
  150. **       In these cases, we need to record that the elem/attr has no
  151. **       namespace so that we will not attempt to prepend a prefix.
  152. **       All namespaces that are used will have a prefix assigned to
  153. **       them -- mod_dav will never set or use the default namespace
  154. **       when generating XML. This means that "no prefix" will always
  155. **       mean "no namespace".
  156. **
  157. **    In both cases, the XML generation will avoid prepending a prefix.
  158. **    For the first case, this means the original prefix/name will be
  159. **    inserted into the output stream. For the latter case, it means
  160. **    the name will have no prefix, and since we never define a default
  161. **    namespace, this means it will have no namespace.
  162. **
  163. ** Note: currently, mod_dav understands the "xmlns" prefix and the
  164. **     "xml:lang" attribute. These are handled specially (they aren't
  165. **     left within the XML tree), so the APR_XML_NS_NONE value won't ever
  166. **     really apply to these values.
  167. */
  168. #define APR_XML_NS_DAV_ID    0    /* namespace ID for "DAV:" */
  169. #define APR_XML_NS_NONE        -10    /* no namespace for this elem/attr */
  170.  
  171. #define APR_XML_NS_ERROR_BASE    -100    /* used only during processing */
  172. #define APR_XML_NS_IS_ERROR(e)    ((e) <= APR_XML_NS_ERROR_BASE)
  173.  
  174.  
  175. typedef struct apr_xml_attr apr_xml_attr;
  176. typedef struct apr_xml_elem apr_xml_elem;
  177. typedef struct apr_xml_doc apr_xml_doc;
  178.  
  179. /** apr_xml_attr: holds a parsed XML attribute */
  180. struct apr_xml_attr {
  181.     /** attribute name */
  182.     const char *name;
  183.     /** index into namespace array */
  184.     int ns;
  185.  
  186.     /** attribute value */
  187.     const char *value;
  188.  
  189.     /** next attribute
  190.      *  @defvar apr_xml_attr *next */
  191.     struct apr_xml_attr *next;
  192. };
  193.  
  194. /** apr_xml_elem: holds a parsed XML element */
  195. struct apr_xml_elem {
  196.     /** element name */
  197.     const char *name;
  198.     /** index into namespace array */
  199.     int ns;
  200.     /** xml:lang for attrs/contents */
  201.     const char *lang;
  202.  
  203.     /** cdata right after start tag */
  204.     apr_text_header first_cdata;
  205.     /** cdata after MY end tag */
  206.     apr_text_header following_cdata;
  207.  
  208.     /** parent element 
  209.      *  @defvar apr_xml_elem *parent */
  210.     struct apr_xml_elem *parent;    
  211.     /** next (sibling) element 
  212.      *  @defvar apr_xml_elem *next */
  213.     struct apr_xml_elem *next;    
  214.     /** first child element 
  215.      *  @defvar apr_xml_elem *first_child */
  216.     struct apr_xml_elem *first_child;
  217.     /** first attribute 
  218.      *  @defvar apr_xml_attr *attr */
  219.     struct apr_xml_attr *attr;        
  220.  
  221.     /* used only during parsing */
  222.     /** last child element 
  223.      *  @defvar apr_xml_elem *last_child */
  224.     struct apr_xml_elem *last_child;
  225.     /** namespaces scoped by this elem 
  226.      *  @defvar apr_xml_ns_scope *ns_scope */
  227.     struct apr_xml_ns_scope *ns_scope;
  228.  
  229.     /* used by modules during request processing */
  230.     /** Place for modules to store private data */
  231.     void *priv;
  232. };
  233.  
  234. #define APR_XML_ELEM_IS_EMPTY(e) ((e)->first_child == NULL && \
  235.                                   (e)->first_cdata.first == NULL)
  236.  
  237. /** apr_xml_doc: holds a parsed XML document */
  238. struct apr_xml_doc {
  239.     /** root element */
  240.     apr_xml_elem *root;    
  241.     /** array of namespaces used */
  242.     apr_array_header_t *namespaces;
  243. };
  244.  
  245.  
  246. typedef struct apr_xml_parser apr_xml_parser;
  247.  
  248. /**
  249.  * Create an XML parser
  250.  * @param pool The pool for allocating the parser and the parse results.
  251.  * @return The new parser.
  252.  */
  253. APU_DECLARE(apr_xml_parser *) apr_xml_parser_create(apr_pool_t *pool);
  254.  
  255. /**
  256.  * Parse a File, producing a xml_doc
  257.  * @param p      The pool for allocating the parse results.
  258.  * @param parser A pointer to *parser (needed so calling function can get
  259.  *               errors), will be set to NULL on successfull completion.
  260.  * @param ppdoc  A pointer to *apr_xml_doc (which has the parsed results in it)
  261.  * @param xmlfd  A file to read from.
  262.  * @param buffer_length Buffer length which would be suitable 
  263.  * @return Any errors found during parsing.
  264.  */
  265. APU_DECLARE(apr_status_t) apr_xml_parse_file(apr_pool_t *p,
  266.                                              apr_xml_parser **parser,
  267.                                              apr_xml_doc **ppdoc,
  268.                                              apr_file_t *xmlfd,
  269.                                              apr_size_t buffer_length);
  270.  
  271.  
  272. /**
  273.  * Feed input into the parser
  274.  * @param parser The XML parser for parsing this data.
  275.  * @param data The data to parse.
  276.  * @param len The length of the data.
  277.  * @return Any errors found during parsing.
  278.  * @remark Use apr_xml_parser_geterror() to get more error information.
  279.  */
  280. APU_DECLARE(apr_status_t) apr_xml_parser_feed(apr_xml_parser *parser,
  281.                                               const char *data,
  282.                                               apr_size_t len);
  283.  
  284. /**
  285.  * Terminate the parsing and return the result
  286.  * @param parser The XML parser for parsing this data.
  287.  * @param pdoc The resulting parse information. May be NULL to simply
  288.  *             terminate the parsing without fetching the info.
  289.  * @return Any errors found during the final stage of parsing.
  290.  * @remark Use apr_xml_parser_geterror() to get more error information.
  291.  */
  292. APU_DECLARE(apr_status_t) apr_xml_parser_done(apr_xml_parser *parser,
  293.                                               apr_xml_doc **pdoc);
  294.  
  295. /**
  296.  * Fetch additional error information from the parser.
  297.  * @param parser The XML parser to query for errors.
  298.  * @param errbuf A buffer for storing error text.
  299.  * @param errbufsize The length of the error text buffer.
  300.  * @return The error buffer
  301.  */
  302. APU_DECLARE(char *) apr_xml_parser_geterror(apr_xml_parser *parser,
  303.                                             char *errbuf,
  304.                                             apr_size_t errbufsize);
  305.  
  306.  
  307. /**
  308.  * Converts an XML element tree to flat text 
  309.  * @param p The pool to allocate out of
  310.  * @param elem The XML element to convert
  311.  * @param style How to covert the XML.  One of:
  312.  * <PRE>
  313.  *     APR_XML_X2T_FULL                start tag, contents, end tag 
  314.  *     APR_XML_X2T_INNER               contents only 
  315.  *     APR_XML_X2T_LANG_INNER          xml:lang + inner contents 
  316.  *     APR_XML_X2T_FULL_NS_LANG        FULL + ns defns + xml:lang 
  317.  * </PRE>
  318.  * @param namespaces The namespace of the current XML element
  319.  * @param ns_map Namespace mapping
  320.  * @param pbuf Buffer to put the converted text into
  321.  * @param psize Size of the converted text
  322.  */
  323. APU_DECLARE(void) apr_xml_to_text(apr_pool_t *p, const apr_xml_elem *elem,
  324.                                   int style, apr_array_header_t *namespaces,
  325.                                   int *ns_map, const char **pbuf,
  326.                                   apr_size_t *psize);
  327.  
  328. /* style argument values: */
  329. #define APR_XML_X2T_FULL         0    /**< start tag, contents, end tag */
  330. #define APR_XML_X2T_INNER        1    /**< contents only */
  331. #define APR_XML_X2T_LANG_INNER   2    /**< xml:lang + inner contents */
  332. #define APR_XML_X2T_FULL_NS_LANG 3    /**< FULL + ns defns + xml:lang */
  333.  
  334. /**
  335.  * empty XML element
  336.  * @param p The pool to allocate out of
  337.  * @param elem The XML element to empty
  338.  * @return the string that was stored in the XML element
  339.  */
  340. APU_DECLARE(const char *) apr_xml_empty_elem(apr_pool_t *p,
  341.                                              const apr_xml_elem *elem);
  342.  
  343. /**
  344.  * quote an XML string
  345.  * Replace '<', '>', and '&' with '<', '>', and '&'.
  346.  * @param p The pool to allocate out of
  347.  * @param s The string to quote
  348.  * @param quotes If quotes is true, then replace '"' with '"'.
  349.  * @return The quoted string
  350.  */
  351. APU_DECLARE(const char *) apr_xml_quote_string(apr_pool_t *p, const char *s,
  352.                                                int quotes);
  353.  
  354. /**
  355.  * Quote an XML element
  356.  * @param p The pool to allocate out of
  357.  * @param elem The element to quote
  358.  */
  359. APU_DECLARE(void) apr_xml_quote_elem(apr_pool_t *p, apr_xml_elem *elem);
  360.  
  361. /* manage an array of unique URIs: apr_xml_insert_uri() and APR_XML_URI_ITEM() */
  362.  
  363. /**
  364.  * return the URI's (existing) index, or insert it and return a new index 
  365.  * @param uri_array array to insert into
  366.  * @param uri The uri to insert
  367.  * @return int The uri's index
  368.  */
  369. APU_DECLARE(int) apr_xml_insert_uri(apr_array_header_t *uri_array,
  370.                                     const char *uri);
  371. #define APR_XML_GET_URI_ITEM(ary, i) (((const char * const *)(ary)->elts)[i])
  372.  
  373. #ifdef __cplusplus
  374. }
  375. #endif
  376. /** @} */
  377. #endif /* APR_XML_H */
  378.